
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD>
   <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
   <META NAME="GENERATOR" CONTENT="Mozilla/4.06 [en] (WinNT; I) [Netscape]">
   <META NAME="ProgId" CONTENT="FrontPage.Editor.Document">
   <TITLE>How to use Orbacus ORB in JADE</TITLE>

<LINK REL ="stylesheet" TYPE="text/css" HREF="stylesheet.css" TITLE="Style">
</HEAD>
<BODY TEXT="#000000" BGCOLOR="#FFFFFF" LINK="#0000FF" VLINK="#0000FF" ALINK="#0000FF">
&nbsp;

<H1 STYLE="border: none; padding: 0in">How to use Orbacus ORB in JADE </H1>
<P STYLE="margin-bottom: 0in; border: none; padding: 0in"><I>Author:
Giovanni Rimassa (University of Parma), Tiziana Trucco (CSELT S.p.A.)
</I></P>
<P STYLE="margin-bottom: 0in; border: none; padding: 0in"><I>Date: <SDFIELD TYPE=DOCINFO SUBTYPE=CHANGE FORMAT=DATE SDNUM="1033;1033;NNNNMMMM D, YYYY">December 18, 2000</SDFIELD></I></P>
<P STYLE="margin-bottom: 0in; border: none; padding: 0in"><I><FONT SIZE=2>Java
platform: <A HREF="http://java.sun.com/j2se/1.3/">Sun JDK 1.2
Windows</A></FONT></I></P>
<P STYLE="margin-bottom: 0in; border: none; padding: 0in"><I><FONT SIZE=2><A HREF="http://jade.cselt.it/">JADE</A>
version 2.1</FONT></I></P>
<P STYLE="margin-bottom: 0in"><BR>
</P>


<P><SPAN lang="EN-GB">
<BR><FONT FACE="Arial,Helvetica">
Since JADE 2.1, FIPA-compliant Message Transport Protocols can be plugged and activated at run-time on any JADE container.
By default, the ORB implementation of Sun is launched on the Main Container of the platform. However, in alternative, 
the ORBacus implementation is also available. 
This tutorial describes how to install and use this ORBacus implementation in JADE.

The ORBacus based IIOP MTP supports three kinds of addresses,
corresponding to three different ways to describe a CORBA Object
Reference in String form.
<ol>
<li><p> <b>IOR:</b> addresses

  <br>These addresses have the form:
  <br>  <code><b>IOR:</b><i>Hex digits</i></code>
  <br>
  where the hexadecimal digits are simply a string representation of
  the memory dump of a CORBA data structure, containing all the
  information needed to find and contact a CORBA object. This address
  kind is the most widely supported, and it's the most complete one
  (it can contain multiple transport profiles, character set
  informations, and so on). Its only disadvantage is not being human
  readable: in particular, in a TCP/IP environment, special utilities
  need to be used to extract the host name and port number from an IOR
  (which could be useful for network configuration purposes).
</p>
<li><p> <b>corbaloc:</b> addresses

  <br>These addresses have the form:
  <br>  <code><b>corbaloc:</b><i>proto</i><b>:</b><i>hostname</i><b>:</b><i>port</i><b>/</b><i>objectID</i></code>
  <br>
  and try to represent a CORBA Object Reference just like an HTTP
  URL. They can be easily read, but they lose a lot of information
  with respect to IOR form, and they make only sense in a TCP/IP
  environment. The <i>proto</i> part denotes the transport protocol to be
  used, and it's optional, defaulting to 'iiop'; the <i>hostname</i> and
  <i>port</i> parts define the IP host and the TCP port where a suitable
  IIOP message must be sent in order to contact the CORBA object. The
  <i>objectID</i> part identifies a specific CORBA object (usually,
  selecting the host and the port will at most select an object
  adapter). Supporting this kind of addresses breaks the server-side
  source code portability that wasthe ultimate goal of the POA
  specification, because there is no concept of 'port' in the POA, to
  keep transport protocol independence: so, this ORBacus based MTP
  uses ORBacus-specific extensions to select the TCP port when
  requested, and creates a different POA for each TCP port.
</p>
<li><p> <b>corbaname:</b> addresses

  <br>These addresses have the form:
  <br>  <code><b>corbaname::</b><i>NShostname</i><b>:</b><i>NSport</i><b>/</b><i>NSName</i><b>#</b><i>objBinding</i></code>
  <br>
  and use the CORBA COS Naming Service as an indirection level, to
  reach a CORBA object that was previously bound into a COSNaming
  Server. The <i>NShostname</i> and <i>NSport</i> parts define the IP host and
  TCP port where an implementation of the <code>COSNaming::NamingContext</code> IDL
  interface is listening. The <i>NSName</i> identifies the specific
  implementation (it defaults to "<i>NameService</i>"). The <i>objBinding</i>
  part, then, describes the binding in the <code>NamingContext</code> object, from
  where the actual CORBA object implementing the <code>FIPA::MTS</code> interface
  can be retrieved. Following the CORBA Interoperable Naming Service
  specification, the <code>objBinding</code> string can contain '.' and '/', to
  specify the 'id' and 'kind' fields of a <code>COSNaming::NameComponent</code>,
  and to describe paths of <code>COSNaming::NameComponent</code> objects.
  When activating a <code>corbaname:</code> address, this MTP implementation
  creates a new <code>FIPA::MTS</code> object and binds it into the given Naming
  Server. Likewise, when deactivating the <code>corbaname:</code> address, the
  binding is removed from the Naming Server.
</p>
</ol>
<p>
When a JADE container is started, it is possible to activate one ore more communication endpoints on it.
<BR>In order to use ORBACUS ORB the following steps must be performed: 
<UL>
<li> Download from the OOC web site <A HREF="http://www.ooc.com">www.ooc.com </A> version 4 of Orbacus for JAVA. At the web site it 's possible to download the complete source code or the precompiled jar files for the ORBacus. 
So far, JADE has been tested with version 4.0.3. </li> 
<li> Download from the JADE site the add-on Orbacus in the download area of JADE. </li>
<li> You can compile the JADE add-on by using its batch file or directly use the included jar file. Notice that if you downloaded the source code then you would also need the jidl (ORBacus IDL compiler).</li> </li>
<li> set the classpath to include the OB.jar (from ORBacus) and the iiopOB.jar (JADE add-on). NOTICE THAT conflict may arise
between the Sun version and ORBacus version if you included also the iiop.jar. This implies that on each container only one
of the two ORB must be used.If you want to use <code>corbaname:</code> addresses, you also have to include in your CLASSPATH the file <code>OBNaming.jar</code> (ORBacus COS Naming Service, available from <A HREF="http://www.ooc.com">www.ooc.com </A></li>
</ul>
At this point in time, an IIOP endpoint that uses an ORBacus-based  IIOP MTP can be activated. 
There are two ways available to activate it:
<ul>
<li> From the command line when you start a JADE container. In this case the following parameter must be specified on the command line. The following line activates a <code>corbaloc:</code> address:
<p><code> -mtp orbacus.MessageTransportProtocol(corbaloc:iiop:<i>hostname</i>:<i>port</i>/<i>name</i>) </code></p>
<p>The following line activates a <code>corbaloc:</code> address:</p>
<p><code> -mtp orbacus.MessageTransportProtocol(corbaname::<i>NShostname</i>:<i>NSport</i>/<i>NSname</i>#<i>objBinding</i>) </code></p>
<li> From the GUI of the RMA as specified later in this tutorial
</ul>
For <code>corbaloc:</code> and <code>corbaname:</code> addresses, the IIOP address where the platform must listen to incoming FIPA messages or the COSNaming Service can be found can be specified. 
This has the big advantage that the address of the platform can be selected by the user and, eventually, might be published on your business card. In other words, there is no more any need to publish the IOR of the agent platform.
When activating a <code>corbaname:</code> address, take care that a COSNaming Service implementation is actually running at the
<i>NSHostname</i>:<i>NSport</i> address, with the <i>NSname</i> Object ID, or the MTP activation will fail.
<p>
When a container starts, it prints on the standard output all the activated MTP addresses, separated by a carriage return. Moreover, it writes the same addresses in a file, named:
MTPs-<i>Container Name</i>.txt.
<p>
Using the -mtp command line option, a transport endpoint lives as long as its container is up; when a container is shut down, all its MTPs are deactivated and the AMS information is updated accordingly. The JADE RMA console enables a more flexible management of the MTPs, allowing to activate and deactivate transport protocols during normal platform operations.
<p>
<b>Configuring MTPs from the graphical management console.</b>
<p>
Select a container from the GUI, click the right button of the mouse and a popup menu appears.

Choose the <code>Install a new MTP</code> option and a dialog will be shown.
Here the following information can be set: the container to install the new MTP on (if different from the selected one), 
the fully qualified name of the class implementing the <code>jade.mtp.MTP</code> interface, 
and (if it is supported by the chosen protocol) the transport address that will be used to contact the new MTP. 
<p>
For example, 
<ul>
<li> in order to install a new IIOP endpoint by using the default JDK 1.2 ORB, one should write 
<code>jade.mtp.iiop.MessageTransportProtocol</code> as the class name and nothing as the address. 
<li> in order to install a new IIOP endpoint by using the ORBacus based implementation, one should write 
<code>orbacus.MessageTransportProtocol</code> as the class name and 
(if the endpoint had to be deployed at host sharon.cselt.it on the TCP port 1234 with an object ID jade) 
<code>corbaloc:iiop:sharon.cselt.it:1234/jade</code> as the transport address.
</ul>
<p>
Choosing Uninstall an MTP shows a dialog where the user can select from a list one of the currently installed MTPs and remove it from the platform.

</FONT> 
<HR>
<CENTER>
<P><FONT FACE="Arial"><FONT SIZE=-1><A HREF="http://jade.cselt.it/">JADE</A>
is a trademark of
<A HREF="http://www.cselt.it">CSELT</A>. <A HREF="http://jade.cselt.it/">JADE</A>
has been developed jointly by <A HREF="http://www.cselt.it">CSELT</A> and
the <A HREF="http://www.ce.unipr.it">Computer Engineering Group</A> of
the <A HREF="http://www.unipr.it">University of Parma</A></FONT></FONT></CENTER>

<BR>&nbsp;
<P><BR>
<BR>
<BR>
<BR>
<BR>
<BR>
</BODY>
</HTML>
